Crate async_io

Async I/O and timers.

This crate provides two tools:

• Async, an adapter for standard networking types (and many other types) to use in async programs.
• Timer, a future or stream that emits timed events.

For concrete async networking types built on top of this crate, see async-net.

Implementation

The first time Async or Timer is used, a thread named “async-io” will be spawned. The purpose of this thread is to wait for I/O events reported by the operating system, and then wake appropriate futures blocked on I/O or timers when they can be resumed.

To wait for the next I/O event, the “async-io” thread uses epoll on Linux/Android/illumos, kqueue on macOS/iOS/BSD, event ports on illumos/Solaris, and IOCP on Windows. That functionality is provided by the polling crate.

However, note that you can also process I/O events and wake futures on any thread using the block_on() function. The “async-io” thread is therefore just a fallback mechanism processing I/O events in case no other threads are.

Examples

Connect to example.com:80, or time out after 10 seconds.

use async_io::{Async, Timer};
use futures_lite::{future::FutureExt, io};

use std::net::{TcpStream, ToSocketAddrs};
use std::time::Duration;

let addr = "example.com:80".to_socket_addrs()?.next().unwrap();

let stream = Async::<TcpStream>::connect(addr).or(async {
    Timer::after(Duration::from_secs(10)).await;
    Err(io::ErrorKind::TimedOut.into())
})
.await?;

Modules

• os
  Platform-specific functionality.

Structs

• Async
  Async adapter for I/O types.
• Readable
  Future for Async::readable.
• ReadableOwned
  Future for Async::readable_owned.
• Timer
  A future or stream that emits timed events.
• Writable
  Future for Async::writable.
• WritableOwned
  Future for Async::writable_owned.

Traits

• IoSafe
  Types whose I/O trait implementations do not drop the underlying I/O source.

Functions

• block_on
  Blocks the current thread on a future, processing I/O events when idle.